{
    title:  'Logging',
    crumbs: [
        { "User's Guide": '../../users/' },
        { 'Configuration': '../configuration.html' },
    ],
}
            <h1>Logging Directives</h1>
            <a id="errorLog"></a>
            <h2>ErrorLog</h2>
            <table class="directive" title="directive">
                <tbody>
                    <tr>
                        <td class="pivot">Description</td>
                        <td>Configure the Appweb diagnostic error log</td>
                    </tr>
                    <tr>
                        <td class="pivot">Synopsis</td>
                        <td>ErrorLog path <br/>
                            &nbsp; &rarr; [size=bytes] <br/>
                            &nbsp; &rarr; [level=0-5] <br/>
                            &nbsp; &rarr; [backup=count] <br/>
                            &nbsp; &rarr; [anew]<br/>
                            &nbsp; &rarr; [stamp=period]</td>
                    </tr>
                    <tr>
                        <td class="pivot">Context</td>
                        <td>Default Server</td>
                    </tr>
                    <tr>
                        <td class="pivot">Example</td>
                        <td>ErrorLog error.log size=1MB level=2 backup=5 anew stamp=1hr</td>
                    </tr>
                    <tr>
                        <td class="pivot">Notes</td>
                        <td>
                            <p>The ErrorLog directive configures the diagnostic error log for Appweb. There is one
                            such error log and all error messages and trace will be written to this log.</p>
                            The given <em>path</em> may be an absolute filename or it may be
                            relative to the Home directory. 
                            <p>The <em>size</em> parameter specifies a maximum size to write to a single log file.
                            The <em>backup</em> parameter indicates how many backup log files to preserve. When the
                            maximum size is exceeded, the log files will be renamed by appending a sequential number
                            from zero up to the given path name. The highest number will be the oldest log file.</p>
                            <p>The <em>anew</em> keyword specifies that a new log file will be created whenever
                            Appweb is restarted.</p>
                            <p>The <em>level</em> argument defines a
                            logging verbosity level between 0 and 5 with 5 being the most verbose.</p>
                            <p>The following levels are generally observed:</p>
                            <table title="levels">
                                <thead>
                                    <tr>
                                        <th>Level</th>
                                        <th>Usage</th>
                                    </tr>
                                </thead>
                                <tbody>
                                    <tr>
                                        <td>0</td>
                                        <td>Essential messages, fatal errors and critical warnings</td>
                                    </tr>
                                    <tr>
                                        <td>1</td>
                                        <td>Hard errors</td>
                                    </tr>
                                    <tr>
                                        <td>2</td>
                                        <td>Configuration setup and soft warnings</td>
                                    </tr>
                                    <tr>
                                        <td>3</td>
                                        <td>Useful informational messages</td>
                                    </tr>
                                    <tr>
                                        <td>4</td>
                                        <td>Debug information</td>
                                    </tr>
                                    <tr>
                                        <td>5</td>
                                        <td>Most verbose level of logging</td>
                                    </tr>
                                </tbody>
                            </table>
                            <p>If Appweb is invoked with a <em>--log</em> or <em>--verbose</em> argument, it will
                            override the ErrorLog directive which will be ignored.</p>
                            <p>A general overview of using log files is discussed in the Administration
                            section on <a href="../logFiles.html">Log Files</a>.</p>
                            <p>The <em>timestamp</em> option controls how frequently time stamps are appended to 
                            the log file. Timestamps are useful to frame the time window in which log file events
                            occurred.</p> 
                        </td>
                    </tr>
                </tbody>
            </table>
            
            <a id="trace"></a>
            <h2>Trace</h2>
            <table class="directive" title="directive">
                <tbody>
                    <tr>
                        <td class="pivot">Description</td>
                        <td>Control the tracing of HTTP requests</td>
                    </tr>
                    <tr>
                        <td class="pivot">Synopsis</td>
                        <td>Trace [rx|tx] <br/>
                            &nbsp; &rarr; connection=level <br/>
                            &nbsp; &rarr; errors=level <br/>
                            &nbsp; &rarr; info=level <br/>
                            &nbsp; &rarr; rxFirst=level <br/>
                            &nbsp; &rarr; rxHeaders=level <br/>
                            &nbsp; &rarr; rxBody=level <br/>
                            &nbsp; &rarr; txFirst=level <br/>
                            &nbsp; &rarr; txHeaders=level <br/>
                            &nbsp; &rarr; txBody=level <br/>
                            &nbsp; &rarr; complete=level <br/>
                            &nbsp; &rarr; content=bytes
                        </td>
                    </tr>
                    <tr>
                        <td class="pivot">Context</td>
                        <td>Default Server</td>
                    </tr>
                    <tr>
                        <td class="pivot">Example</td>
                        <td>Trace errors=2 rxFirst=2 rxHeaders=3 txFirst=3 txHeaders=3 connection=4 <br/>
                            &nbsp; &rarr; info=4 rxBody=5 txBody=5 complete=4 content=10K</td>
                    </tr>
                    <tr>
                        <td class="pivot">Notes</td>
                        <td>
                            <p>The Trace directive controls how HTTP requests are traced to the request log file.
                            The following classes of information can be traces. 
                            <ul>
                                <li>connection &mdash; connection oriented events</li>
                                <li>errors &mdash; request errors resulting in abnormal termination</li>
                                <li>info &mdash; request processing information</li>
                                <li>rxFirst &mdash; first line of the HTTP request header</li>
                                <li>rxHeaders &mdash; full request headers</li>
                                <li>rxBody &mdash; request body content</li>
                                <li>txFirst &mdash; first line of the HTTP response header</li>
                                <li>txHeaders &mdash; full response headers</li>
                                <li>txBody &mdash; response body content</li>
                                <li>complete &mdash; Request completion</li>
                            </ul>
                            <p>For each class, the level defines the log level at which tracing will occur.</p>
                            <p>When tracing is enabled for a HTTP message, the headers and/or body of the message
                            will be written to the log file. Binary body content will be encoded into printable hex
                            characters. Tracing will be limited to at most <em>content</em> bytes per request. 
                            Content size defaults to 40K.</p>
                        </td>
                    </tr>
                </tbody>
            </table>
            <a name="traceLog"></a>
            <h2>TraceLog</h2>
            <table class="directive" title="directive">
                <tbody>
                    <tr>
                        <td class="pivot">Description</td>
                        <td>Configure a request trace log.</td>
                    </tr>
                    <tr>
                        <td class="pivot">Synopsis</td>
                        <td>TraceLog path <br/>
                            &nbsp; &rarr; [anew]<br/>
                            &nbsp; &rarr; [backup=count] <br/>
                            &nbsp; &rarr; [formatter=common|detail]<br/>
                            &nbsp; &rarr; [level=0-5] <br/>
                            &nbsp; &rarr; [size=bytes] <br/>
                            &nbsp; &rarr; [stamp=period] </td>
                    </tr>
                    <tr>
                        <td class="pivot">Context</td>
                        <td>Default Server, Virtual Host, Route</td>
                    </tr>
                    <tr>
                        <td class="pivot">Example</td>
                        <td>TraceLog request.log size=1MB backup=5 anew</td>
                    </tr>
                    <tr>
                        <td class="pivot">Notes</td>
                        <td>
                            <p>The TraceLog directive configures a request trace log that Appweb uses to write
                            request trace information. The given path may be an absolute filename or it may be
                            relative to the Home directory. The TraceLog directive applies per route and is 
                            inherited by default from outer routes in the config file.</p>

                            <p>Two output formats are available. The <em>common</em> formatter writes single-line records
                            in the Common Log standard format. The <em>detail</em> format writes multi-line records
                            with full capture of request and response headers and other details.</p>

                            <p>The <em>size</em> parameter specifies a maximum size to write to a single log file.
                            The <em>backup</em> parameter indicates how many backup log files to preserve. When the
                            maximum size is exceeded, the log files will be renamed by appending a sequential number
                            from zero up to the given path name. The highest number will be the oldest log file.</p>
                            <p>The <em>anew</em> keyword specifies that a new log file will be created whenever
                            Appweb is restarted.</p>
                        </td>
                    </tr>
                </tbody>
            </table>
